home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / C and C++ / Libraries / GUSI / README < prev    next >
Encoding:
Text File  |  1994-01-11  |  12.6 KB  |  276 lines  |  [TEXT/MPS ]

  1.                  G U S I -- Grand Unified Socket Interface
  2.  
  3. INTRODUCTION
  4.  
  5. GUSI is an extension and partial replacement of the MPW C runtime library.
  6. Its main objective is to provide a more or less simple and consistent interface
  7. across the following communication domains:
  8.  
  9. Files                Ordinary Macintosh files and MPW pseudo devices.
  10. Unix                Memory based communication within a single machine
  11. Appletalk        ADSP communication over a network.
  12. PPC                Local and remote connections with the System 7 PPC Toolbox
  13. Internet            TCP and UDP connections over MacTCP.
  14.  
  15. Additionally, GUSI adds some UNIX library calls dealing with files which
  16. were missing, like chdir(), getcwd(), symlink(), and readlink(), and changes
  17. a few other library calls to behave more like their UNIX counterparts.
  18.  
  19. REQUIREMENTS
  20.  
  21. To use GUSI, you need MPW C 3.2 or later. To modify it, you additionally need
  22. MPW C++ 3.2 or later and Perl.
  23.  
  24. COPYING
  25.  
  26. Copyright © 1992, 1993 Matthias Neeracher
  27.  
  28. Permission is granted to anyone to use this software for any purpose on any
  29. computer system, and to redistribute it freely, subject to the following
  30. restrictions:
  31.  
  32. - The author is not responsible for the consequences of use of this software,
  33.   no matter how awful, even if they arise from defects in it.
  34. - The origin of this software must not be misrepresented, either by explicit
  35.   claim or by omission.
  36. - Altered versions must be plainly marked as such, and must not be misrepresented
  37.   as being the original software.
  38.  
  39. WHERE TO BEGIN
  40.  
  41. You should probably start with printing out the documentation in GUSI.ps. Maybe
  42. it helps also to play with the sample programs.
  43.  
  44. BUGS, QUESTIONS, SUGGESTIONS
  45.  
  46. Please report any problems you experience with the code or the documentation to
  47. me. I'd also be interested in hearing about your success stories, if you have
  48. any.
  49.  
  50. MAILING LIST
  51.  
  52. There is now a mailing list for announcing new releases and discussions about how to 
  53. make GUSI change your life. To subscribe, send a mail to <gusi-request@iis.ee.ethz.ch>
  54.  
  55. Matthias Neeracher                    Office:    +41 1 632 51 46
  56. Hohenklingenstrasse 19                Home:     +41 1 341 85 06
  57. 8049 Zuerich                            Email:    <neeri@iis.ee.ethz.ch>
  58. SWITZERLAND
  59.  
  60. RELEASE NOTES
  61.  
  62. Version 1.3.5    11Jan94
  63.  
  64. - Made the semantics of select() conform more closely to their UN*X counterparts.
  65.   In particular, if there is no more data to read/write, a socket is now flagged
  66.   as ready to read/write. In the past, the exception flag was incorrectly used 
  67.   to signal error conditions.
  68. - EBADF is now treated the same way as ESHUTDOWN on write().
  69. - GUSI now handles more than _NFILE stdio FILEs [James Tisdall].
  70. - Fixed several bugs with default arguments and prompts for choose() with files
  71.   [Maki Watanabe].
  72. - chdir() would ignore most errors [Peter Lewis].
  73.  
  74. Version 1.3.4    17Nov93
  75.  
  76. - Fixed a bug in GUSIBuffer which prevented PPC Toolbox sockets from receiving
  77.   more than about 2K of data before crashing.
  78. - fflush() in the MPW stdio library doesn't take no (or -1) for an answer, therefore
  79.   quitting with unsent data in the stdio buffers would cause programs to hang.
  80.   As a workaround, GUSI detects when write() is called twice in a row and 
  81.   ESHUTDOWN would have been returned both times. In this case, GUSI pretends
  82.   the write succeeded the second time.
  83. - The new version of rename introduced in 1.3.3 was buggy in several respects.
  84.   First of all, it would return EINVAL when the call actually had succeeded. 
  85.   Second, rename() was too naive to actually force the correct spelling.
  86.   rename("a", "A"), would work, rename("A", "A"), when the file was actually
  87.   spelled "a" would not.
  88. - rmdir() frivolously walked up a directory before deleting, which for some
  89.   strange reason sometimes actually worked.
  90. - readdir() would return ENOENT when the end of the directory was reached, which
  91.   is contrary to the way UN*X does it.
  92. - GUSI would try to open all network services whose socket families were linked 
  93.   in at a very early stage in the application. This would cause problems for 
  94.   SLIP/PPP (and probably also ARA) users, as for some applications (like MacPerl),
  95.   starting up SLIP every time made little sense. Additionally, initializing
  96.   MacTCP before the rest of the Toolbox would cause crashes with some SLIP 
  97.   implementations. The behaviour of GUSI has now changed so network services
  98.   are only initialized when the first socket is opened or another call necessitates
  99.   it.
  100. - A new socket family has been added in GUSIRemoteConole.o, which is currently not
  101.   documented, so using it is not recommended.
  102.  
  103. Version 1.3.3    24Oct93
  104.  
  105. - Added automatic centering to get directory dialog if rezzed for System 7 only.
  106. - Added a constructor for special files and folders to class TFileSpec.
  107. - Made rename("a", "A") possible.
  108. - Made TFileSpec and consequently GUSI file routines more robust against 
  109.   pathological paths. Path components longer than 63 chars used to trash 
  110.   memory.
  111.  
  112. Version 1.3.2    11Sep93
  113.  
  114. - In the absence of an /etc/services file, endservent() tried to fclose 
  115.   (FILE *) -1, with disastrous consequences. Thanks to Olafur Bragason for
  116.   reporting this bug.
  117. - Paul C. Aitkenhead discovered that accept() for TCP sockets didn't fill
  118.   in the name of the connecting peer. 
  119. - The tests will now initialize QuickDraw by themselves, to take into account
  120.   the fact that when using SIOW, WaitNextEvent might get called before SIOW has
  121.   a chance to initialize the Toolbox.
  122. - As Brad Pickering found out, sends for UDP sockets would by mistake never 
  123.   report errors.
  124.  
  125. Version 1.3.1  09Aug93
  126.  
  127. - Reid Simmons brought to my attention that gethostname() was no longer an
  128.   external symbol. On closer inspection, the same turned out to be true about 
  129.   truncate() and GUSIDefaultSpin(). I had made a few mistakes in my prototypes.
  130.   The new version of the Internalize script should catch this type of error in
  131.   the future.
  132.   
  133. Version 1.3.0    31Jul93
  134.  
  135. - Separated examples into their own folder with their own Makefile. Building
  136.   GUSITest will therefore no longer cause GUSI.o to be rebuilt.
  137. - The Makefile has been generally sanitized. 
  138. - All header files now reside in :includes
  139. - Most headers have changed in rather drastical ways. The BSD headers are now
  140.   taken from net2 and are prototyped. This is initially likely to produce a 
  141.   few errors in your code where typecasts have been missing. In particular, the
  142.   following have changed:
  143.    - bind, connect, accept, and getsockname take address parameters 
  144.       of type (struct sockaddr *).
  145.     - If you had declard any variables as (dirent *), you will have to change 
  146.       that to (struct dirent *).
  147. - The headers have also been adapted so that no symbol from the standard MPW headers
  148.   is ever redefined in an incompatible way (hopefully).
  149. - getserv...() has been enhanced, thanks to code contributed by Sak Wathanasin.
  150.   The new implementation first searches for a file /etc/services in the preferences
  151.   folder, before falling back on the old approach.
  152. - getservent(), setervent(), endservent(), getservbyport(), truncate(), ftruncate(),
  153.   and scandir() were added.
  154. - stat() on a directory now returns the number of files in st_size. Needless to
  155.   say, this is totally nonportable.
  156. - Pathnames where an intermediate folder existed as a file didn't give the
  157.   errors they should have given.
  158. - Another UDP fix.
  159.  
  160. Version 1.2.0    20Jun93
  161.  
  162. - Fixed a disastrous bug with configuration resources. MPW Tools that had no 
  163.   configuration resources would "borrow" resources of other Tools previously
  164.   loaded.
  165. - It is now possible to make the type & creator of newly created file dependent
  166.   on their suffixes (i.e., anything ening in .o can be mapped to 'OBJ '/'MPS ')
  167. - If socket creation fails due to low memory conditions, errno is set correctly
  168. - Opening of the console is now handled more subtly, allowing programmers to link
  169.   GUSI with their custom "Dev:Console" handlers.
  170. - The routine for checking for Command-period is now exported
  171. - getsockname() for UDP sockets in an early stage of their existence would in some
  172.   cases nonsense. Thanks to Paul C. Aitkenhead for discovering.
  173. - Changed sa_constr_ppc. The old version was basically unable to provide a real
  174.   constraint. Hopefully, though, old sa_constr_ppc records are still handled
  175.   correctly.
  176. - Bracketed all headers defining prototypes with #ifdef __cplusplus incantations.
  177.   Thanks to John W. Pope for suggesting this.
  178.   
  179. Version 1.1.1    04Apr93
  180.  
  181. - A few of the declarations in sys/fcntl.h were inconsistent with Fcntl.h and the
  182.   actual behaviour of GUSI, in particular O_CREATE. (thanks to Franklin Chen for
  183.   reporting).
  184. - PAP sockets would lose data when closed.
  185.  
  186. Version 1.1.0    14Mar93
  187.  
  188. - Reorganized the way to specify parts of GUSI to include. There are no specialized
  189.   builds like GUSI_AFU.o anymore. Instead, you specify one or several configuration
  190.   files in addition to GUSI.o in the link. If you just want to include everything 
  191.   possible, use {CLibraries}GUSI_Everything.cfg.
  192. - Added support for the Printer Access Protocol (PAP): You can open a connection
  193.   to the currently chosen LaserWriter with open("Dev:Printer").
  194. - Added support for Dave Peterson's forthcoming inetd.
  195. - Introduced fgetfileinfo().
  196. - All header files are now protected against multiple inclusion, as suggested by
  197.   J.T. Conklin.
  198. - st_nlink in statbufs used to return 1 for both files and folders. While it might 
  199.   be argued that this is true, it breaks some Unix programs. Therefore, the current
  200.   version returns for folders either the number of items the folder contains + 2 or
  201.   the number of subdirectories the folder contains + 2 (the 2 is an Unixism), 
  202.   depending on a flag in the configuration resource (thanks to Charlie Reiman for
  203.   reporting).
  204. - fstat() used to claim that sockets were regular files. This bug had horrible 
  205.   consequences for some Unix software. Now, they correctly declare sockets to be
  206.   such.
  207. - Use FSpMakeFSSpec at some places in TFileSpec if it's available. Added a member
  208.   function Bless() to guarantee the kosherness of a TFileSpec.
  209. - Found a few severe bugs in GUSIBuffer. PPC sockets might work better now.
  210. - Added several new options to the preference resource. To specify which version 
  211.   of the preference resource you want, #define GUSI_PREF_VERSION to the version 
  212.   you want. If you don't, version '0102' is assumed.
  213. - To faciliate changing flags on the fly, programs rezzed with GUSI.r now include
  214.   a TMPL for the version resource.
  215.  
  216. Version 1.0.2    24Jan93
  217.  
  218. - rename() used to sometimes do the wrong thing if both the name and the folder had
  219.   to be changed. I don't think the new version is 100% correct, but it should be 
  220.   better. (thanks to Brad Pickering for reporting)
  221. - choose() for files doesn't count the terminating NULL byte anymore. I hope 
  222.   nobody relied on the old version. (thanks again to Brad Pickering)
  223. - getserv...() and getprotoby...() used to return NULL for the aliases field, which
  224.   is not correct.
  225. - TCP/IP sockets had a horrible bug with fast read/writes. That's what I get for
  226.   not doing my code stealing properly.
  227.  
  228. Version 1.0.1    09Jan93
  229.  
  230. - If a TCP socket returned from accept() was closed, further accepts on the
  231.   parent socket were disabled. Fixed. Thanks to Chen JiaTyan for reporting.
  232. - GUSI configuration resources are now respected
  233. - Programs linked with GUSI now by default automatically call the spin routine
  234.   for every read/write (This can be turned off in the configuration resource).
  235. - Add a chdir()-respecting fsetfileinfo()
  236.  
  237. Version 1.0        20Dec92
  238.  
  239. - Changed the way subset libraries were built.
  240. - Arrange for the GUSI_F variant to be always built.
  241. - Add routines to access FSSpec manipulations from plain C.
  242. - Add correct prototypes to netdb.h.
  243. - Rename GUSIFSp_P.h to TFileSpec.h and make it public.
  244. - Let choose() treat flags consistently for all address families: If CHOOSE_NEW
  245.   or CHOOSE_DIR are specified for a family that doesn't support them, EINVAL
  246.   is returned.
  247. - FileSocketDomain::choose() now treats CHOOSE_DEFAULT correctly
  248. - Add getcwd()
  249. - stat() now considers files with type 'TEXT' as executable (this is certainly
  250.   controversial and might be made configurable in a future version).
  251. - removed GUSIResident, the feature from hell. I forgot twice to specify
  252.   a resident segment for it, and both times it took me almost a week to find
  253.   the bug. The routines formerly in GUSIResident are now in Main.
  254. - fixed a few bugs.
  255. - Updated the documentation.
  256.  
  257. Version 1.0b4    29Oct92
  258.  
  259. Purged (hopefully) the last remaining traces of the obsolete structure name
  260. "direct" (should have been "dirent"). Thanks to Kevin Willey for pointing out
  261. that bug.
  262.  
  263. Version 1.0b3    19Oct92
  264.  
  265. Fixed a few bugs in the test programs
  266.  
  267. Version 1.0b2    05Oct92
  268.  
  269. The documentation is now almost complete.
  270.  
  271. Version 1.0b1    28Sep92
  272.  
  273. This release is somewhat premature. Although I believe the code is already in a
  274. decent shape, the documentation is still in a bad shape. I wouldn't trust the PPC
  275. Toolbox code too much yet.
  276.